<html>
<head>
<title>FreeCC Parser Generator, Version 0.9.2</title>
</head>
<body>
<h1>FreeCC Parser Generator 0.9.2, released 20 November 2008</h1>

<p>This is the third publicly announced release of FreeCC, labelled as version
 0.9.2. Version 0.9 was released on 2 October 2008 and Version 0.9.1 on 22 October 2008.

<p> Version numbers are quite arbitrary, of course. This one is somewhat
 misleading as regards the maturity of the tool. FreeCC is based on forking the
 JavaCC codebase in April of this year, which is basically the same code that was
 released soon afterwards as JavaCC version 4.1.

<p>Hence, FreeCC version 0.9.x is a more advanced version of the JavaCC tool which
is labelled 4.x. In fact, if this work had been done as part of the JavaCC project,
it would be a preview release of JavaCC 5.0.

<h2>Changes since the last release</h2>

<p>Perhaps the most noticeable aspect of this release is that it establishes some new coding 
conventions and also, the accompanying examples have been modified to reflect these 
conventions. See <a href="http://code.google.com/p/freecc/wiki/FreeccConventions">here</a> for more information.

<p>The new INCLUDE_GRAMMAR and INJECT_CODE statements were renamed to INCLUDE and INJECT respectively.

<p>There have been a large number of bugs and assorted glitches fixed. I am not
organized enough to keep track of all this systematically and list them.

<p>There is a rudimentary Ant build task for FreeCC. For examples of usage, see the build.xml.

<h2>Getting Started</h2>

<p>How you would best go about getting started will, I think, depend greatly on
your level of prior experience using JavaCC specifically, and/or other similar
sorts of tools. Besides that, it depends on your learning style.

<h2>If you are new to JavaCC...</h2>

<p>Personally, I began using JavaCC at some point in 2001. At the time, I had
basically zero experience using this kind of tool. Nonetheless, if memory serves,
I got going with it fairly quickly. Even though the documentation was extremely
sparse (and still is) it was fairly easy to get going with it simply by mucking
about with the simple examples that came with the tool. See the Simple1.freecc,
Simple2.freecc, and Simple3.freecc that are in the <code>examples/SimpleExamples</code>
directory. I found that by simply experimenting using these trivial examples
as a starting point, I was able to expand my knowledge and gain some sense of
comfort fairly quickly. Oddly enough, even though JavaCC's main competitor, ANTLR,
has much more documentation, I found that it presented a much steeper learning
curve.

<p>I believe that the best materials available online for familiarizing yourself
with JavaCC would be the <a href="http://www.engr.mun.ca/~theo/JavaCC-FAQ/">FAQ</a>
and <a href="http://www.engr.mun.ca/~theo/JavaCC-Tutorial/">tutorial</a> by
Theodore Norvell.

<h2>If you are an experienced user of JavaCC...</h2>

<p>People who are already comfortable using JavaCC should have little trouble
getting started with FreeCC. In this case, you will be most interested in seeing
what features FreeCC offers beyond what is in JavaCC. A good starting point is
this <a href="http://code.google.com/p/freecc/wiki/NewInFreeCC">Wiki page</a>.
You should certainly have a look at the page on
<a href="http://code.google.com/p/freecc/wiki/CodeInjection">code injection</a>
as well as the page that describes
<a href="http://code.google.com/p/freecc/wiki/TreeBuildingEnhancements">tree
building enhancements</a> in FreeCC.

<p>Some of the examples have been reworked to show how these new features such
as code injection can be put to good use. The simplest example to examine
would be <code>examples/TreeBuildingExamples/eg2.freecc</code>, an example that
is included with JavaCC, but here, has been rewritten to use code injection. You
can then move on and look at eg3.freecc and eg4.freecc to see some other, still quite
simple, examples of how the INJECT instruction can be used.

<p>A much more involved example of the use of new FreeCC features is in the
src/grammars directory. This contains a modified version of the Java 1.5 grammar
included with JavaCC.

<p>Also, you would do well to take a look at the FreeMarker example under examples/freemarker. This contains a new FreeMarker grammar which will supplant the existing one in the FreeMarker 2.4.x release cycle.

<h2>Please Join the Community</h2>

<p>While there is no obligation, of course, FreeCC users are strongly encouraged
to subscribe to the freecc-devel mailing list. You can do so
<a href="http://groups.google.com/group/freecc-devel">here.</a> I am very
interested in receiving user feedback on this work.

<br>
<br>Jonathan Revusky
<br>Palma de Mallorca, Spain
<br>November 2008

</body>
</html>
